docs: document idle-first harness checks#407
Conversation
Add tests verifying worker and groom idle are read-only. Add docs/harness-idle-first.md with integration pattern. Closes #399
![its-saffron[bot]](https://avatars.githubusercontent.com/in/3901073?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
AI Automated Review
Full PR review.
Analysis engine: MiniMax-M2.7@https://litellm.jory.dev/v1 (anthropic) — escalated (fast_low_confidence)
PR PR 407 Review: Document Idle-First Harness Checks
Summary
This PR adds documentation for the idle-first harness check pattern and expands test coverage to verify read-only idle behavior for both worker and groomer modes.
Change-by-Change Findings
1. New Documentation: docs/harness-idle-first.md
- Purpose: Documents the idle-first integration pattern for harnesses calling the
next-taskendpoint - Content: Covers endpoint behavior, integration examples (curl + pseudo-code), key properties (read-only, cheap, no lease mutation), groom mode idle, non-goals, and source code references
- Conventions check: Uses generic agent names (
saffron,example-agent) consistent with AGENTS.md rule "No agent-specific names in generic docs" - Changelog entry present: Yes (2026-06-16 entry at bottom)
- Issue reference: Correctly links to PR 399 in header
2. Test Additions: src/app/api/agents/[agentName]/next-task/route.test.ts
- Worker idle tests (6 tests): Cover empty issue queue, empty PR-fix queue, short reason format, and verify read-only behavior (no issue/PR-fix/lease mutations)
- Groom idle tests (5 tests): Cover no-candidate idle, correct reason string, and verify groom mode does not query PR-fix queue or leases
- Test quality: Uses proper mock setup, verifies mock interactions, and covers both modes
Standards Compliance
| Standard | Status |
|---|---|
| No agent-specific names in generic docs | ✅ Pass — uses generic patterns |
| Documentation includes history/changelog | ✅ Pass — history section present |
| Tests use repository conventions | ✅ Pass — follows existing test patterns |
| Code standards (validation, error handling) | N/A — documentation and tests only |
Linked Issue Fit
Issue PR 399 acceptance criteria are satisfied:
| Criteria | Verification |
|---|---|
| worker schedule can exit early | ✅ Documented with lane=normal endpoint |
| groomer schedule can exit early | ✅ Documented with mode=groom endpoint |
| tests cover empty queue state | ✅ 6 worker idle tests added |
| tests cover empty follow-up state | ✅ Tests verify PR-fix queue reads without mutation |
| docs show idle-first pattern | ✅ Complete docs with examples, pseudo-code, key properties |
Evidence Provider Findings
No evidence provider output provided.
Tool Harness Findings
No tool harness output provided.
CI Check Results
✅ Docker Build: success
✅ Validate: success
Unknowns / Needs Verification
None identified — PR is purely documentation and tests; no runtime behavior changes requiring verification.
Recommendation
Approve. This PR correctly addresses issue PR 399 by adding comprehensive documentation and test coverage for the idle-first harness check pattern. All acceptance criteria are met, CI passes, and the changes follow repository conventions.
1 participant
Closes #399